container: Clarify the forall/foreach documentation

Try to make the difference between these two functions
clearer.

diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 2f4cf2a08a95686d29f96a55f487aeedbf5c8710..69ffbd7df17ba3b8f31b5f29bbfeb3b934598669 100644 (file)
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -2387,12 +2387,14 @@ gtk_container_class_handle_border_width (GtkContainerClass *klass)
  * @callback: (scope call) (closure callback_data): a callback
  * @callback_data: callback user data
  *
- * Invokes @callback on each child of @container, including children
- * that are considered “internal” (implementation details of the
- * container). “Internal” children generally weren’t added by the user
- * of the container, but were added by the container implementation
- * itself.  Most applications should use gtk_container_foreach(),
- * rather than gtk_container_forall().
+ * Invokes @callback on each direct child of @container, including
+ * children that are considered “internal” (implementation details
+ * of the container). “Internal” children generally weren’t added
+ * by the user of the container, but were added by the container
+ * implementation itself.
+ *
+ * Most applications should use gtk_container_foreach(), rather
+ * than gtk_container_forall().
  **/
 void
 gtk_container_forall (GtkContainer *container,
@@ -2416,10 +2418,15 @@ gtk_container_forall (GtkContainer *container,
  * @callback: (scope call):  a callback
  * @callback_data: callback user data
  *
- * Invokes @callback on each non-internal child of @container. See
- * gtk_container_forall() for details on what constitutes an
- * “internal” child.  Most applications should use
- * gtk_container_foreach(), rather than gtk_container_forall().
+ * Invokes @callback on each non-internal child of @container.
+ * See gtk_container_forall() for details on what constitutes
+ * an “internal” child. For all practical purposes, this function
+ * should iterate over precisely those child widgets that were
+ * added to the container by the application with explicit add()
+ * calls.
+ *
+ * Most applications should use gtk_container_foreach(),
+ * rather than gtk_container_forall().
  **/
 void
 gtk_container_foreach (GtkContainer *container,